Resolver

Data Structures
struct	CMResolverRegisteredMethodDescription

Macros
#define	NQ_RESOLVER_IPV4   4
#define	NQ_RESOLVER_IPV6   6
#define	NQ_RESOLVER_NONE   0
#define	NQ_RESOLVER_DNS   1
#define	NQ_RESOLVER_NETBIOS   2
#define	NQ_RESOLVER_EXTERNAL_METHOD   5
#define	NQ_RESOLVER_DNS_DC   8
#define	NQ_RESOLVER_NETBIOS_DC   10
#define	NQ_RESOLVER_WSD   12

Typedefs
typedef NQ_INT(*	CMResolverNameToIpA )(const NQ_CHAR *name, void *ip, NQ_COUNT index)
typedef NQ_INT(*	CMResolverNameToIp )(const NQ_WCHAR *name, void *ip, NQ_COUNT index)
typedef NQ_BOOL(*	CMResolverIpToNameA )(NQ_CHAR *name, const void *ip, NQ_INT ipType)
typedef NQ_BOOL(*	CMResolverIpToName )(NQ_WCHAR *name, const void *ip, NQ_INT ipType)

Functions
void	cmResolverSetExternalA (CMResolverNameToIpA nameToIp, CMResolverIpToNameA ipToName)
void	cmResolverSetExternal (CMResolverNameToIp nameToIp, CMResolverIpToName ipToName)
const NQ_WCHAR *	cmResolverGetHostName (const NQ_IPADDRESS *ip)
const NQ_IPADDRESS *	cmResolverGetHostIps (const NQ_WCHAR *dnsList, const NQ_WCHAR *host, NQ_INT *numIps)
const NQ_WCHAR *	cmResolverGetDCName (const NQ_WCHAR *domain, const NQ_WCHAR *dnsList, NQ_INT *numDCs)
void	cmResolverEnableMethod (NQ_INT type, NQ_BOOL unicast, NQ_BOOL multicast)
NQ_BOOL	cmResolverRegisterExternalMethod (const CMResolverRegisteredMethodDescription *pMethod)
NQ_BOOL	cmResolverUpdateExternalMethodsPriority (NQ_INT requiredPriority)

Detailed Description

Macro Definition Documentation

#define NQ_RESOLVER_IPV4   4

The resolved address is IPV4.

#define NQ_RESOLVER_IPV6   6

The resolved address is IPV6.

#define NQ_RESOLVER_NONE   0

No address resolved. This value designates a resolution failure.

#define NQ_RESOLVER_DNS   1

Mechanism type is DNS.

#define NQ_RESOLVER_NETBIOS   2

Mechanism type is NetBIOS.

#define NQ_RESOLVER_EXTERNAL_METHOD   5

Mechanism type not known, external method set by the user.

#define NQ_RESOLVER_DNS_DC   8

Mechanism type is DNS DC.

#define NQ_RESOLVER_NETBIOS_DC   10

Mechanism type is NetBIOS DC.

#define NQ_RESOLVER_WSD   12

Mechanism type is WS-Discovery.

Typedef Documentation

typedef NQ_INT(* CMResolverNameToIpA)(const NQ_CHAR *name, void *ip, NQ_COUNT index)

This function prototype designates a callback for resolving host IP address by its name. NQ uses this callback for external resolution.

Parameters

name	The name of the host to resolve.
index	Index of the resolved IP address. External resolver may resolve multiple IP addresses for the same name. When external resolution is required, NQ subsequently calls this function with 'index' values incrementing, starting from zero. External resolver should return the appropriate IP address or it should should fail the call when an 'index' result is not available.

Returns

One of the following values:

• NQ_RESOLVER_IPV4. This means that 'index' designates an IPv4 address.
• NQ_RESOLVER_IPV6. This means that 'index' designates an IPv6 address.
• NQ_RESOLVER_NONE. This means that either resolution failed of the 'index' value is out of range.

Note

This is an ASCII version of CMResolverNameToIp()

typedef NQ_INT(* CMResolverNameToIp)(const NQ_WCHAR *name, void *ip, NQ_COUNT index)

This function prototype designates a callback for resolving host IP address by its name. NQ uses this callback for external resolution.

Parameters

name	The name of the host to resolve.
index	Index of the resolved IP address. External resolver may resolve multiple IP addresses for the same name. When external resolution is required, NQ subsequently calls this function with 'index' values incrementing, starting from zero. External resolver should return the appropriate IP address or it should should fail the call when an 'index' result is not available.

Returns

One of the following values:

• NQ_RESOLVER_IPV4 This means that 'index' designates an IPv4 address.
• NQ_RESOLVER_IPV6 This means that 'index' designates an IPv6 address.
• NQ_RESOLVER_NONE This means that either resolution failed of the 'index' value is out of range.

typedef NQ_BOOL(* CMResolverIpToNameA)(NQ_CHAR *name, const void *ip, NQ_INT ipType)

This function prototype designates a callback for resolving host name by its IP address. NQ uses this callback for external resolution.

Parameters

name	Buffer for the resolved name.
ip	Pointer to IP address. This pointer designates either NQ_IPADDRESS4, NQ_IPADDRESS4 type or NQ_IPADDRESS6, NQ_IPADDRESS6 type depending on the 'type' argument below.
ipType	IP address type. This value can be either NQ_RESOLVER_IPV4 or NQ_RESOLVER_IPV6. It defines the format of the 'ip' argument.

Returns

TRUE on success, FALSE on failure.

Note

This is an ASCII version of CMResolverIpToName()

typedef NQ_BOOL(* CMResolverIpToName)(NQ_WCHAR *name, const void *ip, NQ_INT ipType)

This function prototype designates a callback for resolving host name by its IP address. NQ uses this callback for external resolution.

Parameters

name	Buffer for the resolved name.
ip	Pointer to IP address. This pointer designates either NQ_IPADDRESS4, NQ_IPADDRESS4 type or NQ_IPADDRESS6, NQ_IPADDRESS6 type depending on the 'type' argument below.
ipType	IP address type. This value can be either NQ_RESOLVER_IPV4 or NQ_RESOLVER_IPV6. It defines the format of the 'ip' argument.

Returns

TRUE on success, FALSE on failure.

Function Documentation

void cmResolverSetExternalA	(	CMResolverNameToIpA	nameToIp,
		CMResolverIpToNameA	ipToName
	)

This function extends NQ's name-to-IP and IP-to-name resolver. NQ attempts to use its internal resolution methods first:

• NetBIOS Naming Service;
• DNS;
• LLMNR. If none of the above succeeds, NQ attempts an external resolver. By calling this function application can enable or disable an external resolving mechanism.

NQ uses callback pointers as follows:

• First, NQ attempts internal methods. If at least one of them succeeded, the external method is not used.
• If a Unicode callback was specified, it is used.
• If a Unicode callback pointer was not specified or its pointer was set to NULL, NQ uses ASCII callback.
• If neither Unicode nor ASCII callback were specified or both pointers are NULL, NQ skips external resolution.
• The approach above applies independently to each of name-to-IP and IP-to-name resolution.

Parameters

nameToIp	Pointer to a function that resolves host IP by its name. This function signature should conform to the CMResolverNameToIp prototype. This value can be NULL. In this case, NQ will fail external name-to-IP resolution.
ipToName	Pointer to a function that resolves host name by its IP. This function signature should conform to the CMResolverIpToName prototype. This value can be NULL. In this case, NQ will fail external IP-to-name resolution.

void cmResolverSetExternal	(	CMResolverNameToIp	nameToIp,
		CMResolverIpToName	ipToName
	)

This function extends NQ's name-to-IP and IP-to-name resolver. NQ attempts to use its internal resolution methods first:

• NetBIOS Naming Service;
• DNS;
• LLMNR. If none of the above succeeds, NQ attempts an external resolver. By calling this function application can enable or disable an external resolving mechanism.

NQ uses callback pointers as follows:

• First, NQ attempts internal methods. If at least one of them succeeded, the external method is not used.
• If a Unicode callback was specified, it is used.
• If a Unicode callback pointer was not specified or its pointer was set to NULL, NQ uses ASCII callback.
• If neither Unicode nor ASCII callback were specified or both pointers are NULL, NQ skips external resolution.
• The approach above applies independently to each of name-to-IP and IP-to-name resolution.

Parameters

nameToIp	Pointer to a function that resolves host IP by its name. This function signature should conform to the CMResolverNameToIp prototype. This value can be NULL. In this case, NQ will fail external name-to-IP resolution.
ipToName	Pointer to a function that resolves host name by its IP. This function signature should conform to the CMResolverIpToName prototype. This value can be NULL. In this case, NQ will fail external IP-to-name resolution.

const NQ_WCHAR* cmResolverGetHostName

(

const NQ_IPADDRESS *

ip

)

This function resolves host by its IP and return its name.

Host name is created in allocated memory so that it is caller's responsibility to free this memory.

NQ uses several unicast and multicast methods for this resolution. First, it attempts all unicast methods concurrently. Depending on compilation parameters those methods may be:

• DNS queries to one or more DNS servers;
• NetBIOS query to one or more WINS. If none of the above succeeded, NQ concurrently attempts multicast methods as:
• LLMNR;
• NetBIOS broadcasts. If those methods did not succeed, NQ calls external method if this method has been installed in cmResolverRegisterExternalMethod() call.

  Parameters

  ip	Pointer to host IP address.

  Returns

  Pointer to newly created host name or NULL on failure.

  Note

  It is caller's responsibility to release this name.

const NQ_IPADDRESS* cmResolverGetHostIps	(	const NQ_WCHAR *	dnsList,
		const NQ_WCHAR *	host,
		NQ_INT *	numIps
	)

This function resolves host by its name and return its IP addresses.

The array of IP addresses is created in allocated memory so that it is caller's responsibility to free this memory.

NQ uses several unicast and multicast methods for this resolution. First, it attempts all unicast methods concurrently. Depending on compilation parameters those methods may be:

• DNS queries to one or more DNS servers;
• NetBIOS query to one or more WINS. If none of the above succeeded, NQ concurrently attempts multicast methods as:
• LLMNR;
• NetBIOS broadcasts. If those methods did not succeed, NQ calls external method if this method has been installed in cmResolverRegisterExternalMethod() call.

  Parameters

  host	Pointer to host name to resolve.
  numIps	Pointer to variable that on exit gets the number of resolved IP addresses.
  dnsList	DNS ips to register and prepare methods.

  Returns

  Pointer to an array of IP addresses or NULL on error. The size of array is placed into the variable pointed by numIps.

  Note

  It is caller's responsibility to release this array. To release this array the caller need to call the cmMemoryFree() function.

const NQ_WCHAR* cmResolverGetDCName	(	const NQ_WCHAR *	domain,
		const NQ_WCHAR *	dnsList,
		NQ_INT *	numDCs
	)

This function resolves domain's DC and return its name.

DC name is created in allocated memory so that it is caller's responsibility to free this memory.

NQ uses several unicast and multicast methods for this resolution. First, it attempts all unicast methods concurrently. Depending on compilation parameters those methods may be:

• DNS queries to one or more DNS servers;
• NetBIOS query to one or more WINS. If none of the above succeeded, NQ concurrently attempts multicast methods as:
• NetBIOS broadcasts. If those methods did not succeed, NQ calls external method if this method has been installed in cmResolverRegisterExternalMethod() call.

  Parameters

  domain	Pointer to domain name.
  dnsList	Semicolon delimited list of DNS servers.
  numDCs	Pointer to variable that on exit gets the number of resolved DC names.

  Returns

  Pointer to newly created DC name or NULL on failure.

  Note

  It is caller's responsibility to release this name. To release the name call cmMemoryFree()

void cmResolverEnableMethod	(	NQ_INT	type,
		NQ_BOOL	unicast,
		NQ_BOOL	multicast
	)

Resolver uses different methods (mechanisms) to resolve host IP(s) by name or to resolve host name by IP. Each mechanism may use either unicasts or multicasts. NQ attempts all possible unicasts first. Then, if unicasts failed, it attempts multicasts. Currently, the following mechanisms are available:

Method	DNS	NetBIOS
Unicast	DNS server query	WINS query
Multicast	LLMNR	local broadcast

All methods are initially enabled on NQ startup. This function allows to enable or disable a particular one in run-time.

Parameters

type	Resolution type. This may be one of the following: NQ_RESOLVER_DNS, NQ_RESOLVER_NETBIOS, NQ_RESOLVER_EXTERNAL_METHOD, NQ_RESOLVER_DNS_DC, NQ_RESOLVER_NETBIOS_DC, NQ_RESOLVER_WSD.
unicast	When this parameter is TRUE, NQ enables unicast method (s) of the given type. When this parameter is FALSE., NQ disables unicast method(s).
multicast	When this parameter is TRUE, NQ enables multicast method(s) of the given type. When this parameter is FALSE., NQ disables multicast method(s).

NQ_BOOL cmResolverRegisterExternalMethod

(

const CMResolverRegisteredMethodDescription *

pMethod

)

Resolver uses DNS and NET BIOS to resolve host IP(s) by name or to resolve host name by IP. This function enables adding another resolution method. A method is defined using the CMResolverRegisteredMethodDescription Structure. See structure description with different members. Not all functions have to be defined, but notice following guidelines:

1. Must define at least one request function - request by name or request by IP
2. If a request function is defined, then the corresponding response function must be defined as well.
3. If defined timeout value is too long it might cause a delay in setup process.
4. Resolver methods are not executed all at once. Registered method will be executed according to defined priority. See the CMResolverRegisteredMethod structure.

   Parameters

   pMethod

   resolution method.

   Returns

   TRUE - on registration success. FALSE otherwise.

NQ_BOOL cmResolverUpdateExternalMethodsPriority

(

NQ_INT

requiredPriority

)

This function enables run time control on the order of resolver methods execution. In resolver point of view three groups of methods exist: unicast methods, multicast methods, external methods. External methods are all methods that were registered by the user. Each group of methods is executed separately and if no reply is received the next group is executed.

Parameters

requiredPriority

This parameter takes the following values: Execute external methods before all other methods. Execute external methods after unicast methods and before multicast methods. Execute external methods only if all other resolution methods failed.

Returns

TRUE - on success. FALSE otherwise.